\chapter{How to contribute}

In this chapter, we give some guidelines to people who think they
might want to contribute to \sysname{}.  Specifically, we elaborate on
the main objectives with \sysname{}, which will then dictate what kind
of contributions we are interested in, and how to determine whether a
contribution is worthwhile to work on.

The important objectives of \sysname{} are (in no particular order):

\begin{itemize}
\item Simplicity.  We want the design to be as simple as possible.  We
  tolerate exceptions to this rule only if there is some major
  advantage to them, such as performance.  For example objects of
  type \texttt{cons}, \texttt{fixnum}, \texttt{character}, and
  \texttt{single-float} are not standard objects, because we are
  convinced that it would be hard to get good performance if they
  were.
\item Maintainability.  We want the code to be readable and
  understandable.  This objective implies not only that the code
  should have comments explaining the techniques being used, but also
  that the code should be idiomatic, divided into reasonable-sized
  units with appropriate names, and respect the guidelines in
  \refChap{chap-general-commonlisp-style-guide}, and
  \refChap{sicl-specific-style-guide}.
\item Debuggability.  We want \sysname{} to be the preferred
  \commonlisp{} implementation for debugging application code.  This
  objective implies that error messages should be excellent, and they
  should refer to source locations whenever possible.  But it also
  means that we must be able to set breakpoints for the purpose of
  pausing the execution and examining variable values.
\item Features.  We are obviously interested in \sysname{} having the
  features that application programmers expect.  However, there are
  some features that we are not particularly interested in, because we
  do not intend to use them ourselves, and they would likely increase
  our own maintenance burden.  Features like that would be better to
  implement as separate repositories that interested users could add
  if they like.  In particular, we are not interested in maintaining a
  foreign-function interface (FFI).
\item Performance.  Performance is a major objective for \sysname{}.
  However, we do not want maximum performance at all cost.  Other
  objectives must be respected as well.  In particular, we want to try
  to avoid code for handling specific optimization situations if there
  is a more general optimization technique that can handle several
  such situations.  For example, while some \commonlisp{}
  implementation can avoid checking the argument count by having
  several special entry points in each function, and avoid keyword
  arguments by introducing many compiler macros, our technique for
  call-site optimization is more general, and subsumes these other
  techniques, as well as some others.
\end{itemize}

In the following sections, we elaborate on some ideas for
contributions in each of the domains mentioned above.

\section{Features}

\subsection{Fast Fourier Transform (FFT)}

We would like to provide a good FFT library.  The implementation can
use threads (for large vectors) and/or special SIMD instructions.  The
best implementation strategy is probably to write a \commonlisp{}
function that generates machine code.

\subsection{POSIX interface}

\sysname{} (and other \commonlisp{} implementations as well) need to
communicate with the operating system, and POSIX is a standard
interface for doing so.  We would like to see a complete POSIX
interface as described here: http://metamodular.com/POSIX-API/index.html

\subsection{Profiling}

We need code for profiling application programs.  Such code involves
the profiling interface itself, but also the compiler infrastructure
that allows code to be profiled.  But an ordinary profiler and a
statistical profiler are needed.

\subsection{Coverage}

We also need code to create coverage statistics for application
programs.  As with profiling, such code involves both the interface to
the facility and compiler infrastructure.

\subsection{General array displacement}

The standard \commonlisp{} feature for array displacement is very
limited.  Only an interval of the base array can be expressed.  We
would like an extension of this facility so that the elements of an
array with some particular dimensions would be determined by some
arbitrary function being applied to valid indices of the array.
Ordinary array displacement can then be expressed with this function
being a closure, closing over the base array.  But there does not have
to be any base array involved at all.  The function can generate the
``elements'' in some arbitrary way.

\section{Performance}

Perhaps the most important aspect of performance improvements is to
make sure they are really making a significant difference to overall
performance, compared to the increased complexity and maintenance
burden they might introduce.

The first step in determining whether some code meant to improve
performance is to devise a way to measure whether the aspect being
optimized is exercised often enough to justify the optimization.  We
strongly advise against the technique that consists of acting upon
some intuition, and using the optimization code to test the
intuition.  We advise against it, because the code then has a tendency
to remain in the repository, even if it turns out that the performance
improvement is marginal, and more code implies a greater maintenance
burden.  We recommend the article \cite{10.1145/3213770}
John Ousterhout on performance measure that discusses in great length
the importance of performance measures, and how they go beyond simple
profiling.

Performance improvements meant to speed up compilation are not high
priority for us.  The idea behind this policy is that compilation is
not done very often, so performance of compilation is usually not a
main issue.  Furthermore, such improvements usually imply more code to
maintain.  We are much more interested in improvements to the code
generated by the compiler.  Such improvements will benefit application
performance, but also compiler performance, since the compiler is
another application.
